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Section 1. Before you start 
What is this tutorial about? 


This tutorial covers the fundamental concepts of data manipulation in DB2 
databases, including the following topics: 

° Changing data 

° Querying a database across multiple tables 

° Querying tables across multiple databases (i.e., federated databases) 

° Using DB2 SQL functions 
° Using common table expressions 
° Determining when to use cursors in an SQL program 
° Identifying types of cursors 
° Identifying the scopes of cursors 
° Manipulating cursors 
° Managing a unit of work (i.e., a transaction) 

This is the second in a series of seven tutorials that you can use to help prepare 
for the DB2 UDB V8.1 Family Application Development Certification exam 
(Exam 703). The material in this tutorial primarily covers the objectives in 
Section 2 of the exam, entitled "Data manipulation." You can view these 
objectives at: http://www.ibm.com/certify/tests/obj703.shtml. 

You do not need a copy of DB2 Universal Database to complete this tutorial. 
However, you can download a free trial version of IBM DB2 Universal Database 
Enterprise Edition for reference. 


Who should take this tutorial? 


To take the DB2 UDB V8.1 Family Application Development exam, you must 
have already passed the DB2 UDB V8.1 Family Fundamentals exam (Exam 
700). You can use the DB2 Family Fundamentals tutorial series (see Resources 
on page 25) to prepare for that test. It is a very popular tutorial series that has 
helped many people understand the fundamentals of the DB2 family of 
products. 

This tutorial is one of the tools that can help you prepare for Exam 703. You 
should also review Resources on page 25 at the end of this tutorial for more 
information. 

Application development involves data retrieval and manipulation. In DB2, these 
processes include several methods. While these methods can be programmed 
in different languages, the concepts remain same no matter what the 
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implementation language. This tutorial is the first step you should take before 
embarking on programming applications for DB2. 
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Section 2. Changing and accessing data 


Changing data 

Changing data is a key process to understand when designing a database 
application. It depends on several factors: 

° The data model and metadata (What are the catalog data, types, limits, 
checks, etc. that you must deal with?) 

° Business requirements (How do you need to identify and modify the data in 
the database?) 

° Authorization and security at the user, table, and column level (Is a particular 
change allowed?) 

° Interfaces to access the data (How do you interface with the changing data?) 

Which DB2 capabilities should you use in the design of an application? System 
catalog data cannot be modified by the user. Catalog tables and views store 
metadata about the logical and physical definition of the data. The sysibm 
schema owns the tables, while views for these tables are owned by the syscat 
schema. You can query the catalog to get useful information. In order to make 
appropriate choices, you need to consider both the database design and target 
environments for your application. For example, you can choose to enforce 
some business rules in your database design instead of including the logic in 
your application. 

The capabilities you use and the extent to which you use them can vary greatly. 
The capabilities that you need to consider include: 

° Accessing data using: 

° Embedded SQL, including embedded SQL for Java (SQLJ) 

° DB2 Call Level Interface (DB2 CLI), Open Database Connectivity 
(ODBC), and Java Database Connectivity (JDBC) 

° Microsoft specifications 
° Perl DBI 
° Query products 


° Controlling data values using: 

° Data types (built-in or user-defined) 

° Table check constraints 
° Referential integrity constraints 
° Views using the check option 
° Application logic and variable types 


° Controlling the relationship between data values using: 
° Referential integrity constraints 
° Triggers 


Page 4 of 26 


Database manipulation 



DB2 Information Management Software 


http://www-136.ibm.com/developerworks/db2 


° Application logic 


° Executing programs at the server using: 
° Stored procedures 

° User-defined functions 
° Triggers 


The key advantage in transferring logic focused on data from the application to 
the database is that your application becomes more independent of the data. 
The logic surrounding your data is centralized in one place, the database. This 
means that you can change data or data logic once and affect all applications 
that depend on that data immediately. 

This latter advantage is very powerful, but you must also consider that any data 
logic put into the database affects all users of the data equally. You must 
consider whether the rules and constraints that you wish to impose on the data 
apply to all users of the data or just the users of a single application. 

Your application requirements may also help you decide whether to enforce 
rules at the database or at the application. For example, you may need to 
process validation errors on data entry in a specific order. In general, you 
should do this type of data validation in the application code. You should also 
consider the computing environment where the application is used. You need to 
consider the difference between performing logic on the client machines and 
running the logic on the (usually more powerful) database server machines 
using either stored procedures, UDFs, or a combination of both. In some cases, 
the correct approach is to include enforcement in both the application (perhaps 
due to application-specific requirements) and in the database (perhaps due to 
other interactive uses outside the application). 


Accessing data 

In a relational database, you must use SQL to access your desired data. 
Flowever, you have a choice as to how to integrate that SQL into your 
application. You can choose from the following interfaces and their supported 
languages: 

° Embedded SQL 
° C/C++ 

° COBOL 
° FORTRAN 

° The Java language (via SQLJ or JDBC) 

° REXX 

° DB2 CLI and ODBC 

° Microsoft specifications, including ADO, RDO, and OLE DB 
° Visual Basic, Visual C++ , and .NET languages 
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° Perl DBI 
° Perl 

° Query products like Lotus Approach, IBM Query Management Facility, 
Microsoft Access, or Microsoft Excel 

Your program must establish a connection to the target database server before 
it can run any executable SQL statements. This connection identifies both the 
authorization ID of the user who is running the program and the name of the 
database server on which the program is to be run. Generally, your application 
process can only connect to one database server at a time; this server is called 
the current server. However, your application can connect to multiple database 
servers within a multisite update environment. In this case, only one server can 
be the current server. 

Your program can establish a connection to a database server either explicitly, 
using a connect statement, or implicitly, by connecting to the default database 
server. Java applications can also establish a connection through a 

Connection instance. 


Querying a database across multiple tables 

You can query data from one or more tables using a select statement. You 
need proper authorization to access the data that you query. The data returned 
is known as a result set. 

A select statement only specifies the criteria for the data that a result set must 
fetch. It does not specify the manner in which DB2 returns it. The DB2 optimizer 
makes the latter decision by constructing an access plan based on current 
database statistics from the system catalog tables and the type of plans it has 
been instructed to consider. 

Let's look at some sample select statements. The following statement selects 
all store names and product names from the store and product tables: 


SELECT a.store_name, b.product_name from STORE a, PRODUCT b 

store_name is a column in the table named store. Product_name is a 
column in the table named product. 

Let's look at another example. In the employee table, we'll select the 
department number (workdept) and maximum departmental salary (salary) 
for all departments whose maximum salary is less than the average salary in all 
other departments: 


SELECT WORKDEPT, MAX(SALARY) 
FROM EMPLOYEE EMP_COR 
GROUP BY WORKDEPT 
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HAVING MAX(SALARY) < (SELECT AVG(SALARY) 
FROM EMPLOYEE 

WHERE NOT WORKDEPT = EMP_COR.WORKDEPT) 


Querying tables across multiple federated databases 

A federated system is designed to make it easy to access data, regardless of 
where that data is stored. This is accomplished by creating nicknames for all 
data sources (tables and views) that the user might want to access. 

A DB2 federated system is a distributed computing system controlled by a 
federated server. In a DB2 installation, any number of DB2 instances can be 
configured to function as federated servers. 

The federated system also includes multiple data sources to which the 
federated server sends queries. Each data source consists of an instance of a 
relational database management system plus the database or databases that 
the instance supports. The data sources in a DB2 federated system can include 
Oracle instances along with instances of the members of the DB2 family. 

The data sources are semi-autonomous. For example, the federated server can 
send queries to Oracle data sources at the same time that Oracle applications 
are accessing those same data sources. A DB2 federated system does not 
monopolize or restrict access to Oracle or other data sources (beyond integrity 
and locking constraints). 

To end users and client applications, the data sources appear as a single, 
collective database. Behind the scenes, the users and applications are 
interfacing with the federated database that is within the federated server. To 
obtain data from the data sources, they submit queries in DB2 SQL to the 
federated database. DB2 then distributes the queries to the appropriate data 
sources. DB2 also provides access plans for optimizing the queries. In some 
cases, these plans call for processing the queries at the federated server rather 
than at the data source. Finally, DB2 collects the requested data and passes it 
to the users and applications. 

Queries submitted from the federated server to data sources must be read-only. 
To write to a data source (for example, to update a data source table), users 
and applications must use the data source's own SQL in a special mode called 
pass through. 

For example, imagine that the nickname dept represents the remote table 
Europe .person.dept. You can use the command select * from dept 

to query information in the remote table. All the underlying metadata is stored in 
the federated system catalog as part of setup and configuration. 

To select, insert, and update data using a nickname, the privileges held by the 
authorization ID of the statement must include authorization at both the 
nickname level and authorization at the underlying table object database level. 
Here's how you would grant or revoke permissions for a nickname on certain 
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indexes from a user named Eileen: 


GRANT INDEX ON <nickname> TO USER Eileen 
REVOKE INDEX ON <nickname> FROM USER Eileen 

You can use nicknames to create local summary tables, as follows: 


CREATE TABLE <tablename> LIKE <nickname> DEFINITION ONLY 

You can create federated views using nicknames as follows: 


CREATE FEDERATED VIEW <viewname> AS SELECT <column>.. 

FROM <table>, <nickname>, <view> WHERE <expression> 

You can use the SET option like (set node, 

varchar_no_trailing_blanks, plan_hints) to alter nicknames, as 
follows: 


ALTER NICKNAME OPTIONS ( SET varchar_no_trailing_blanks 'y') 

Pass-through sessions allow clients connect to the databases using a server's 
native API or SQL dialect. When using objects in a pass-through session, you 
use the server's full name, not a nickname. 
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Section 3. Functions and expressions 


What are DB2 SQL functions? 

A database function is a relationship between a set of input data values and a 
set of result values. There are two types of functions: built-in and user-defined. 

° Built-in SQL functions are provided with the database manager. They 
provide a single result value and are identified as part of the sysibm 
schema. Examples of built-in SQL functions include column functions such 
as avg, operator functions such as +, casting functions such as decimal, 
and other functions, such as substr. 

° User-defined functions are functions that are registered to a database in 
syscat.functions (using the create function statement). 
User-defined functions are never part of the sysibm schema. One such set 
of functions is provided with the database manager in a schema called 

SYSFUN. 

DB2 allows users and application developers to extend the functionality of the 
database system by applying their own function definitions in the database 
engine itself. Applications based on user-defined functions perform better than 
applications that retrieve rows from the database and apply those functions on 
the retrieved data. Extending database functions also lets the database exploit 
the same functions in the engine that an application uses, providing more 
synergy between application and database. The use of functions contributes to 
higher productivity for application developers because it is more object oriented 
For example, you may store the price for a product in U.S. dollars, but you may 
want a particular application to quote the price in U.K. pounds. You can use a 
function to accomplish this: 


SELECT unit_price, currency('UKunit_price) from product where product_id = ? 


FENCED and NOT-FENCED modes 


You can create functions in C/C++, the Java language, or OLE. A function can 
run in fenced or not-fenced modes. You should develop a function in 
fenced mode before migrating to not-fenced mode. A not-fenced process 
is faster, as it uses DB2 agent memory, whereas a fenced process runs in its 
own db2udf process. A fenced process uses shared memory to communicate 
with the calling agent, fenced functions are stored in sqilib/function and 
unfenced functions are stored in sqilib/unfenced. 
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DB2-supplied SQL functions 

Let's look at examples of a few SQL functions. Our first example selects the title 
and price for all books in a table. If the price for a given title is null, the price 
shown is 0.00. 


SELECT title, COALESCE(price, 0.00) AS price 
FROM titles; 


Next, we'll see an example that returns a company name and the number of 
characters in that company's name: 


SELECT CompanyName, LENGTH(CompanyName) 
FROM CUSTOMERS 


Now let's see how we can return the five rightmost characters of each author's 
first name: 


SELECT RIGHT(au_fname, 5) 
FROM AUTHORS 


This next example, using the project table, sets the host variable average 
( decimal (5,2)) to the average staffing level (prstaff) of projects in the 
department (deptno) called D11. 


SELECT AVG(PRSTAFF) 

INTO :AVERAGE 
FROM PROJECT 
WHERE DEPTNO = 'Dll' 

There are many other SQL functions defined in DB2 SQL Reference manual. 
You can always write your own SQL function if DB2 does not provide one. 


Using common table expressions 

A common table expression is a local temporary table that can be referenced 
many times in an SQL statement. This temporary table only exists for the 
duration of the SQL statements that define it. Every time the common table is 
referenced, the results will be the same. A temporary table is defined during an 
SQL statement using the with clause. Here's the syntax: 


WITH <Common namel> AS ( <SELECT Expression>), <Common name2> 

AS (<SELECT Expression), & SELECT <column> FROM <table_name> <where_clause> 
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<tabie_name> is either a table in the database or a <common name> defined 
by a SQL statement including a with clause. Here's an example: 


WITH prod_quantity AS 

( SELECT product_id, SUM (quantity) as quantity 
FROM customer_order_item 
GROUP BY product_id 

) , 


totals AS 

( SELECT -1 as product_id, SUM(quantity) AS total 
) 

SELECT product_id, quantity 
FROM prod_quantity 
UNION 

SELECT product_id, totals 
FROM totals 
ORDER BY 1 DESC 


In the above example, prod_quantity is defined as a common table 
expression. It is used along with a common table expression called totals. 
The final select statement selects from both common table expressions. 

Let's now look at another example: 


WITH 

PAYLEVEL AS 

(SELECT EMPNO, EDLEVEL, YEAR(HIREDATE) AS HIREYEAR, 

SALARY+BONUS + COMM AS TOTAL_PAY 

FROM EMPLOYEE 

WHERE EDLEVEL > 16), 

PAYBYED (EDUC_LEVEL, YEAR_OF_HIRE, AVG_TOTAL_PAY) AS 
(SELECT EDLEVEL, HIREYEAR, AVG(TOTAL_PAY) 

FROM PAYLEVEL 

GROUP BY EDLEVEL, HIREYEAR) 

SELECT EMPNO, EDLEVEL, YEAR_OF_HIRE, TOTAL_PAY, DECIMAL(AVG_TOTAL_PAY,7,2) 
FROM PAYLEVEL, PAYBYED 
WHERE EDLEVEL = EDUC_LEVEL 

AND HIREYEAR= YEAR_OF_HIRE 
AND TOTAL_PAY < AVG_TOTAL_PAY 


This common table expression includes paylevel. This result table includes 
an employee number, the year that the person was hired, the total pay for that 
employee, and his or her education level. Only rows for employees with an 
education level greater than 16 are included. 

The listing also includes a common table expression with the name paybyed 
(short for "pay by education"). It uses the paylevel table to determine the 
education level, hire year, and average pay of employees hired in the same 
year who have identical education levels. The columns returned by this table 
have been given different names (educ_level, for example) from the column 
names used in the select list. 
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Finally, we get to the actual query that produces the desired result. The two 
tables (paylevel, paybyed) are joined to determine those individuals who 
have a salary that is less than the average pay for people hired in the same 
year. Note that paybyed is based on paylevel, so paylevel is effectively 
accessed twice in the complete statement. Both times the same set of rows are 
used in evaluating the query. 

After you define a common table expression, you can use it in an SQL 
statement as you would any other table. You can use common table expression 
as many times as you wish. You can even create a common table expression 
based on a previously created common table expression. 
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Section 4. When to use cursors in an SQL program 


What is a cursor? When do you need one? 

A cursor is the mechanism used to manipulate multiple-row answer sets from a 
DB2 query. There are two situations in which you need a cursor: 

° When a query returns more than one row. 

A select statement with an into clause is very simple to code, but allows 
only one row to be returned. There is no clause in a select statement that 
allows multiple rows to be processed directly, so a cursor must be used. 

° When you want to update or delete one or more rows, but need to examine 
their contents first. 

The simplest way to update or delete rows is to use a statement like this: 

UPDATE staff SET salary = salary * 1.10 WHERE id = 100 
Or DELETE FROM staff WHERE id = 100. 

However, these statements, called searched updates or deletes, don't allow 
the program to check the contents of the rows before updating or deleting. 
You could instead use a cursor in conjunction with a positioned update or 
delete. The latter are also known as update where Current of and 
Delete where Current of , where Current Of refers to the row at which 
the cursor is currently positioned. 

To use a cursor, you must declare it, open it, fetch rows from it one at a time, 
(optionally) update or delete the rows at which it is positioned, and close it. We'll 
see more details and examples in this and later sections. 


How cursor support varies by DB2 interface 

Cursor support and terminology varies among the various DB2 programming 
interfaces. Let's take a brief look at the differences. Later, in Manipulating 
cursors on page 19, we'll look at some examples for embedded SQL. 

Basic support for cursors is provided through the SQL language itself, via the 

declare cursor, open, fetch, and close statements. 

You can perform positioned updates and deletes through the following syntax: 


Update [or Delete] . . . Where Current Of <cursor name> 
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Various interfaces build on SQL's cursor support in various ways. Traditional 
programming languages such as C, C++, and COBOL provide explicit support 
for the declaration and use of cursors in static and dynamic embedded SQL. 
Rows can only be processed one at a time in a forward direction. 

The SQL Procedure Language supports cursors much as C does, but with the 
with return clause added to support returning a result set to the caller of a 
stored procedure. 

In the DB2 Call Level Interface (CLI), cursors are not explicitly declared, but CLI 
creates them automatically when the SQLExecute () or SQLExecDirect () 
functions are invoked. CLI provides additional capabilities that build on cursor 
support, such as the ability to scroll backwards, to receive an array of rows at 
one time, and to move forward by more than one row. 

In JDBC, a cursor is created automatically when a ResuitSet object is 
created. Additional capability is available that is similar to that in CLI. 

SQLJ's cursor support is a essentially a blend of what's in JDBC and SQL, but 
in SQLJ the equivalent of a cursor is called an iterator. 

Interactive tools such as the DB2 Command Line Processor (CLP) and Control 
Center do not let you use cursors directly. However, the tools themselves use 
cursors. When you execute a select statement through CLP, or do a sample 
contents request for a table in the Control Center, a cursor is used to return the 
rows. 


A simple example: Cursor usage in static embedded 
SQL 


Before we discuss cursors further, let's look at an example of a very simple 
cursor in static embedded SQL (a C program). 


EXEC SQL DECLARE cO CURSOR FOR SELECT deptnumb, deptname FROM org; 

EXEC SQL OPEN cO; 

EXEC SQL FETCH cO INTO :deptnumb, :deptname; 

while (sqlca.sqlcode != 100) /* continue until the end of the result set */ 

{ 

printf(" %8d %-14s\n", deptnumb, deptname); 

EXEC SQL FETCH cO INTO :deptnumb, :deptname; 

> 


EXEC SQL CLOSE cO; 

This code prints the number and name of every department in the org table. 

The declare cursor statement provides the query to be used, and the open 
statement prepares the result set for the query. A fetch statement is used 
repeatedly to move the values of the result set columns into program variables, 
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one row at a time, until the end of the result set is reached (sqlcode = 
+ 100 ) , at which point the cursor is closed. 
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Section 5. Identifying types of cursors 
Cursor characteristics 

There are three primary characteristics of cursors: 

° The cursor type : read-only, updatable, or ambiguous. 

° The cursor direction(s): forward-only or scrollable. 

° The cursor scope. 

We'll discuss these characteristics in the next few panels. 


Cursor type 

DB2 handles each of the three cursor types somewhat differently, with the 
differences being primarily in the realm of performance. Let's look at each of 
them. 

Read-only cursors 

When DB2 knows that a cursor is read-only, certain performance advantages 
can apply: 

° DB2 is usually able to perform record blocking to retrieve multiple rows from 
the server at one time, and does not need to worry about acquiring locks that 
allow rows to be updated. 

° DB2 can sometimes choose a better access plan for the query. 

If you know that a cursor will not be used for updating or deleting rows, you 
should designate it as read-only by adding for read only (or FOR FETCH 
only) to the select statement for the cursor. A cursor will also be 
(automatically) classified as read-only if its select statement is a join of 
multiple tables or includes such clauses as order by or group by. 

Updatable cursors 

A cursor is updatable if the for update clause is specified in its select 
statement, meaning that rows will be updated via an update where Current 
of statement. There can only be one table (or view) referenced in the select 
statement. Because it must maintain data integrity, DB2 can only perform a 
minimal amount of optimization for updatable cursors. 

The term deletable cursor is used in the SQL Reference as a way to help define 
updatable cursors; the two terms mean almost the same thing. See the 
description of declare cursor in the SQL Reference for details. 
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Ambiguous cursors 

As the name suggests, a cursor is ambiguous when DB2 cannot determine from 
the cursor definition whether it is read-only or updatable -- in other words, when 
the cursor's select statement has neither for read only nor for update 
specified. For an ambiguous cursor, DB2 chooses whether to do record 
blocking for the select based on the value of the blocking option on the bind 
command for the application. If blocking is performed but updates occur, there 
is a negative performance impact, so it's always best to avoid ambiguous 
cursors when possible. 


Cursor direction 


The cursor support for DB2 embedded SQL applications allows only one row to 
be processed at a time, and only in a forward direction. In other words, each 
fetch statement returns the next row of the result set to the application, and 
there is no other way for the application to obtain rows via the cursor. 

CLI and the Java platform support scrollable cursors. These cursors can be 
positioned at an absolute row number in the result set (either forward or 
backward from the current position) or moved a relative number of rows 
(forward or backward) from the current position. For more information on 
scrollable cursors, see the fourth and fifth tutorials in this series (on ODBC/CLI 
and the Java platform, respectively, see Resources on page25 ). 


Cursor scope 

When we talk about the cursor scope, we mean the period during which it is 
available for fetching rows. That period begins when the cursor's open 
statement has completed successfully. By default, the scope of the cursor ends 
when the cursor is closed or when a commit is executed. As we'll see on the 
next panel, having a commit end the scope can be a nuisance, but there's a 
way around it. 


WITH HOLD cursors 


Usually, applications should be written to have commit statements executed 
fairly frequently. These commits cause locks to be released and they minimize 
concurrency issues between applications. Committing can cause a problem 
when it comes to cursors, however. This is where with hold comes in. 

As an example, consider an application in which an SQL statement reads 
10,000 rows using a cursor. The application checks each row's contents and 
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updates the row to set the value of a status column. Waiting to commit until all 
10,000 rows have been processed could cause lock conflicts, so it commits 
after every 20 rows. By default, however, the commit closes the cursor, so the 
position in the result set would be lost and the application would have to do 
some special processing to continue properly from where it left off. 

The solution to this problem is to change the cursor definition to include the 
with hold clause. This causes a commit to leave the cursor open and avoid 
releasing locks necessary to maintain the cursor's positioning. In other words, 
with hold extends the scope of a cursor beyond a commit. Here's an 
example of a with hold cursor: 


declare Cl cursor with hold for select * from staff 

with hold has no effect on what happens to a cursor during a rollback. The 
cursor is closed and all associated locks are released. 
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Section 6. Manipulating cursors 


Overview of cursor processing 

In this section, we'll look more closely at how cursors are used in embedded 
SQL applications. The basic steps, once again, are declare, open, fetch, 
update/delete (optional), and close. 

To help understand the concept of a cursor, assume that DB2 builds a result 
table to hold all the rows retrieved by executing a select statement. A cursor 
makes rows from the result table available to an application by identifying or 
pointing to a current row of this table. When a cursor is used, an application can 
retrieve each row sequentially from the result table until an end-of-data 
condition (that is, the not found condition, sqlcode +100 or sqlstate 
02000) is reached. The set of rows obtained as a result of executing the 
select statement can consist of zero, one, or more rows depending on the 
number of rows that satisfy the search condition. 


Declaring a cursor in embedded SQL 

The syntax of the declare cursor statement is very simple. Here's an 
example for static SQL: 


declare Cl cursor for select * from staff 


The use of the statement can be a bit confusing, however, because the 
statement is not executable. In other words, the statement is handled 
exclusively by the preparation phase of the embedded application, and when 
the declare statement is reached during program execution, nothing happens. 
The work gets done when the cursor is opened. The only requirement is that the 
declare cursor statement appear before the open statement in the source 
file. It does not even need to be located within the same C function, for 
example. Every cursor name must be unique within the source file in which it is 
declared. 

If you're using dynamic SQL, the declare cursor statement is a bit different. 
Instead of including the syntax of the select statement, you would use a 
statement name. That statement name must match the name used when 
preparing the related select statement. For example: 


EXEC SQL PREPARE stmtl FROM :stringStmt; 
EXEC SQL DECLARE c3 CURSOR FOR stmtl; 
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Opening a cursor in embedded SQL 

Opening a cursor prepares the rows of the query result set for use by the 
program. It also positions the cursor before the first result row, though that row 
is not accessible by the program until a fetch is executed. 

Often, the open is where the bulk of the query execution time is spent, 
particularly if there's an order by or group by clause in the select. 

The syntax of an open statement is very simple. To open a cursor named cO, 
you'd use the following: 


open cO 


Fetching a cursor in embedded SQL 

Executing a fetch against a cursor causes the next row of the result set to be 
made available to the program, usually by placing the values of the result set 
columns into host variables. The nth column in the result set is placed in the nth 
host variable in the fetch. 

For example, if a cursor cO is declared for Select name, dept, id from 
staff , the statement Fetch cO into :hvi, :hv2, : hv3 will place the 
value of the name column into hvl, dept into hv2, and id into hv3. 

If any result set column is nullable, a second host identifier (the null indicator) 
should be used, and DB2 will store a negative value in that variable to represent 
a null value being returned. For example, changing the previous example to 
Fetch cO into :hvl, :hv2 :hv2ind, : hv3 would allow the program to 
know if an employee has a null department. 

Usually a fetch is placed within a program loop that is written to continue until 
an sqlcode of +100 is returned. At that point, all rows in the result set will have 
been fetched. 


Updating and deleting rows with a cursor 

As previously mentioned, a positioned update or delete can be done on the row 
at which the cursor is positioned. A fetch must have been performed previously 
and not returned a sqlcode of +100 (or an error). Every row in the result set 
can be processed in this manner - or none of them can, or any number in 
between. Flere's an example: 
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exec sql declare cursor cO for select name, salary from staff for update of dept; 
exec sql fetch cO into :hvname, :hvsal; 

/* there might be program logic here to check the employee name and salary */ 

/* and only execute the update if some criteria apply */ 

exec sql update staff set dept = :newdept where current of cO; 


This code retrieves employee information from the STAFF table and allows an 
employee's department to be updated. The declare cursor statement 
provides the query, listing the name and salary columns as the columns to be 
retrieved, and indicates that the dept column may be updated in some rows. 
The fetch statement places the employee and salary values in program 
variables. The update statement is used to change the value of the dept 
column in the previously fetched row to the value in the program variable 
newdept. 

Although not shown here, program logic would normally be used to loop until 
the end of the result set was reached, and might have been used to only update 
certain rows. 


Closing a cursor 

Closing a cursor frees the internal storage for the cursor and makes the cursor 
unavailable for further use. The syntax is very simple: 


close cO 


By default, closing a cursor does not free the locks it holds. To do so, add the 

with release clause: 


close cO with release 


This makes DB2 try to release all read locks. However, DB2 will keep all locks 
on updated rows and may need to keep some read locks for other operations or 
activities. 

The cursor can be closed at any time when it's open - that is, there is no need 
to fetch the entire result set before closing the cursor. Once a cursor is closed, it 
can be opened again, and it will behave as if it had not previously been used. 
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Section 7. Managing a unit of work 
What is a transaction? 


The term unit of work, or UOW, is synonymous with the concept of a 
transaction. It is defined as zero or more SQL queries that execute as a single 
atomic operation. For example, when a customer makes an online purchase 
from the IBM Web site, there are three steps that must be carried out: 

1. The inventory of the IBM Web mall must be updated. 

2. The customer must be charged for the items purchased. 

3. Each item purchased must be shipped. 

What would happen if the inventory records were updated and the customer 
was charged, but a shipping order entry was never created? Not only would you 
have an angry customer who never received his or her purchase, but you would 
introduce an inaccuracy into the inventory. Thus, all SQL queries for the 
purchase must be defined as a single atomic operation. 


Steps in a transaction 

Let's see what steps need to go into a DB2 transaction. Before you start, a 
connection must be established with the database against which the transaction 
will execute. 

Start the transaction with an executable statement. An executable statement 
always occurs within a transaction. If a program contains an executable 
statement after a transaction ends, it starts a new transaction. The following are 
not executable statements: 


BEGIN DECLARE SECTION 
END DECLARE SECTION 
INCLUDE SQLCA 
INCLUDE SQLDA 
DECLARE CURSOR 
WHENEVER 

End the transaction in the following way: 


COMMIT 

ROLLBACK 


The commit statement ends the transaction and makes the changes visible to 
other processes. Remember, you should commit regularly and do so exclusively 
before program termination. DB2 automatically rolls back transactions if you do 
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not explicitly commit them on Windows operating systems. On other operating 
systems, DB2 commits all pending transactions during program termination 
automatically. 

The rollback statement returns the database to the state it was in before the 
transaction ran. The rollback prevents the changes being applied to the 
database after the last transaction commits. This ensures that either all 
operations in the transaction are committed, or none are. DB2 rolls back 
changes under following conditions: 

° A log full condition 

° A system condition that causes the system process to end 

To avoid loop failure, use whenever sqlwarning continue or whenever 
sqlerror continue before a rollback statement. A rollback statement has 
no effect on contents of host variables. 

You should terminate your application by taking the following steps: 

° End your current transaction by commit or rollback 
° Release your connection by issuing a connect reset statement 
° Free up resources (temporary storage, data structures, shared memory etc.) 

You can have multiple transactions in an application. Within a transaction, you 
can have multiple connections to the databases. 


Connections and transactions 


Programming interfaces have two types of connections: transactional and 
nontransactional. Although DB2 supports these concepts, you should be aware 
that there is really only one type of connection to the database - a transactional 
connection. Thus, every SQL query is part of a transaction. When you run in 
nontransactional mode, the programming interface you are using has enabled a 
feature called autocommit which issues a commit statement implicitly after 
every SQL operation. You must ensure that you do not have autocommit 
enabled if your UOW has multiple queries. 


Savepoints and transactions 

A savepoint is a mechanism for undoing work performed by the DBMS when a 
database request fails. Savepoints make non-atomic database requests behave 
atomically. If an error occurs during execution, the savepoint can be used to 
undo changes made by the transaction between the time the savepoint was 
started and the time when the savepoint rollback was requested. 
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A savepoint allows you to group several SQL statements into a single 
executable block. Before the first substatement of the block is executed, a 
request to start a savepoint block is required. If one of the substatements ends 
in an error, only that substatement will be rolled back. This provides more 
granularity than a compound SQL statement, in which a single error causes the 
entire block to end in an error and rolls back the entire compound SQL 
statement. At the end of a savepoint block of statements, you can either release 
the savepoint or roll back to the savepoint. 

Let's look at some SQL statements that enable you to create and control 
savepoints. To set a savepoint, issue a savepoint SQL statement. To improve 
the clarity of your code, you can choose a meaningful name for the savepoint. 
For example: 


SAVEPOINT savepoint1 ON ROLLBACK RETAIN CURSORS 


To release a savepoint, issue a release savepoint SQL statement. For 
example: 


RELEASE SAVEPOINT savepointl 


If you do not explicitly release a savepoint with a release savepoint SQL 
statement, it is released at the end of the transaction. 

To roll back to a savepoint, issue a rollback to savepoint sql 
statement. For example: 


ROLLBACK TO SAVEPOINT savepointl 
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Section 8. Conclusion 


Summary 

In this tutorial, you learned many concepts on data manipulation strategies. You 
learned how to: 

° Access the data in multiple tables 
° Access the data in federated systems 
° Use SQL functions 
° Use common tables 
° Use cursors 
° Program with transactions 


While this tutorial focused on concepts, further tutorials in this series describe 
all the interfaces used to perform data manipulation. 


Resources 

° For more information on the DB2 UDB V8.1 Family Application Development 
Certification exam (Exam 703), see IBM DB2 Information Management - 
Training and certification (http://www.ibm.com/software/data/education/) for 
information on classes, certifications available and additional resources. 

° As mentioned earlier, this tutorial is just one tutorial in a series of seven to 
help you prepare for the DB2 UDB V8.1 Family Application Development 
Certification exam (Exam 703). The complete list of all tutorials in this series 
is provided below: 

1. Database objects and Programming Methods 

2. Data Manipulation 

3. Embedded SQL Programming 

4. ODBC/C LI Programming 

5. Java Programming 

6. Advanced Programming 

7. User-Defined Routines 

° Before you take the certification exam (DB2 UDB V8.1 Application 
Development, Exam 703) for which this tutorial was created to help you 
prepare, you should have already passed the DB2 V8.1 Family 
Fundamentals certification exam (Exam 700). Use the DB2 V8.1 Family 
Fundamentals certification prep tutorial series to prepare for that exam. A set 
of six tutorials covers the following topics: 

° DB2 planning 

° DB2 security 
° Accessing DB2 UDB data 
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° Working with DB2 UDB data 
° Working with DB2 UDB objects 
° Data concurrency 

° Use the DB2 V8.1 Database Administration certification prep tutorial series 
to prepare for the DB2 UDB V8.1 for Linux, UNIX and Windows Database 
Administration certification exam (Exam 701). A set of six tutorials covers the 
following topics: 

° Server management 
° Data placement 
° Database access 
° Monitoring DB2 activity 
° DB2 utilities 
° Backup and recovery 

° You can learn more about data manipulation from the DB2 Information 
Center. Look particularly to these sections: 

° DB2 Version 8 CLI Guide and Reference, Part 1. See especially Chapter 
5: Cursors. 

° DB2 Version 8 SQL Reference, Volume 2. This covers the SQL 
statements related to cursors. 

° DB2 Version 8 Application Development Guide: Programming Client 
Applications. This covers cursors in different programming environments. 

° Also check out the sample programs that come with DB2. These are shipped 
in sqilib/samples, with various subdirectories for C, JDBC, etc. 

° Read the DB2 UDB v8 Application Development Certification Guide, by 
David Martineau, Steve Sanyal, Kevin Gashyna, and Mike Kyprianou 
(International Business Machines Corporation, 2003). 

° Check out developerWorks Subscription for one-stop access to a 
comprehensive portfolio of the latest IBM software from DB2, Lotus, 

Rational, Tivoli, and WebSphere, allowing you to maximize ROI and lower 
your labor costs, leading to superior productivity. 


Feedback 


Colophon 

This tutorial was written entirely in XML, using the developerWorks Toot-O-Matic tutorial 
generator. The open source Toot-O-Matic tool is an XSLT stylesheet and several XSLT 
extension functions that convert an XML file into a number of HTML pages, a zip file, JPEG 
heading graphics, and two PDF files. Our ability to generate multiple text and binary formats 
from a single source file illustrates the power and flexibility of XML. (It also saves our 
production team a great deal of time and effort.) 

For more information about the Toot-O-Matic, visit 
www- 106 .ibm.com/developerworks/xml/library/x-toot/ . 
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